//-----------------------------------------------------------------------
// <copyright file="SetPermissions.cs" company="Microsoft">
// Copyright (c) Microsoft Corporation.  All rights reserved.
// THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY 
// KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
// PARTICULAR PURPOSE.
// </copyright>
// <author>Andy Reeves</author>
// <email>andyr</email>
// <date>2004-03-23</date>
// <summary>Sets permissions on the specified MessageQueue.</summary>
//-----------------------------------------------------------------------

namespace Microsoft.Sdc.Tasks.MessageQueue
{
    using System;
    using System.Xml;
    using System.Globalization;
    using System.Messaging;
    using Microsoft.Build.Framework;

    /// <summary>
    /// Sets permissions on the specified MessageQueue.
    /// </summary>
    /// <remarks>
    /// <code><![CDATA[<MessageQueue.SetPermissions QueuePath="queuePath" DenyPermission="denyPermission" UserName="userName" AccessRight="accessRight" />]]></code>
    /// <para>where:</para>
    /// <para><i>queuePath (Required)</i></para>
    /// <para>
    /// The message queue that the permissions changes will apply to. The path must be prefixed by the machine name (or "." to represent the local computer). 
    /// See <see cref="System.Messaging.MessageQueue.Path"/> for more details.
    /// </para>
    /// <para><i>denyPermission</i></para>
    /// <para>
    /// Allows the specified access right to either be granted (if set to "false") or revoked (if set to "true") for the specified user. Defaults to "true".
    /// </para>
    /// <para><i>userName</i></para>
    /// <para>
    /// The individual, group, or computer that is to get additional rights to the queue or have rights to the queue removed.
    /// </para>
    /// <para><i>accessRight</i></para>
    /// <para>
    /// The specific access right to be granted or revoked for the specified user. See <see cref="Microsoft.Sdc.Tasks.MessageQueue.SetPermissions.AccessRight"/> for valid values.
    /// </para>
    /// </remarks>
    /// <example>
    /// <code><![CDATA[
    /// <Project>
    ///     <Target Name="Test">
    ///         <MessageQueue.SetPermissions
    ///             QueuePath=".\\TempQueue" 
    ///             UserName="myUser"
    ///             AccessRight="GenericRead" />
    ///     </Target>
    /// </Project>
    /// ]]></code>    
    /// </example>
    public class SetPermissions : TaskBase
    {
        private string queuePath;
        private bool denyPermission;
        private string userName;
        private string accessRight;

        /// <summary>
        /// Initializes a new instance of the SetPermissions class.
        /// </summary>
        public SetPermissions()
        {
        }

        #region Public Properties

        /// <summary>
        /// The message queue that the permissions changes will apply to.
        /// </summary>
        /// <value>The path must be prefixed by the machine name (or "." to represent the local computer). 
        /// See <see cref="System.Messaging.MessageQueue.Path"/> for more details.</value>
        [Required]
        public string QueuePath
        {
            get
            {
                return (this.queuePath == null ? String.Empty : this.queuePath);
            }

            set
            {
                this.queuePath = value;
            }
        }

        /// <summary>
        /// Allows the specified access right to either be granted or revoked for the specified user.
        /// </summary>
        /// <value>Set to true to revoke the specified access right, or false to grant the specified access right. Defaults to false.</value>
        public bool DenyPermission
        {
            get
            {
                return (this.denyPermission);
            }

            set
            {
                this.denyPermission = value;
            }
        }

        /// <summary>
        /// The individual, group, or computer that gets additional rights to the queue or has them revoked (depending on the value of DenyPermission).
        /// </summary>
        /// <value>The user can be any valid trustee, which includes individual users, groups of users, or a computer. If the user is an individual, use the format DOMAIN\ user for the user parameter. You can specify "." for the user parameter to indicate the local computer.</value>
        public string UserName
        {
            get
            {
                return (this.userName == null ? String.Empty : this.userName);
            }

            set
            {
                this.userName = value;
            }
        }

        /// <summary>
        /// The access right to grant the specified user on the specified queue. If the DenyPermission property is set to true,
        /// this access right will be revoked from the specified user, otherwise it will be granted.
        /// </summary>
        /// <value>Can be any of the following:
        /// "ChangeQueuePermissions"    - The right to modify queue permissions
        /// "DeleteJournalMessage"        - The right to delete messages from the journal queue
        /// "DeleteMessage"                - The right to delete messages from the queue 
        /// "DeleteQueue"                - The right to delete the queue 
        /// "FullControl"                - Full rights to the queue. A union of all other rights in the enumeration. 
        /// "GenericRead"                - A combination of GetQueueProperties, GetQueuePermissions, ReceiveMessage, and ReceiveJournalMessage. 
        /// "GenericWrite"                - A combination of GetQueueProperties, GetQueuePermissions, and WriteMessage. 
        /// "GetQueuePermissions"        - The right to read queue permissions. 
        /// "GetQueueProperties"        - The right to read properties of the queue. 
        /// "PeekMessage"                - The right to peek messages from the queue. 
        /// "ReceiveJournalMessage"        - The right to receive messages from the journal queue. This includes the rights to delete and peek messages from the journal queue. 
        /// "ReceiveMessage"            - The right to receive messages from the queue. This includes the rights to delete and peek messages. 
        /// "SetQueueProperties"        - The right to modify properties of the queue 
        /// "TakeQueueOwnership"        - The right to take ownership of the queue. 
        /// "WriteMessage"                - The right to send messages to the queue. 
        /// </value>
        public string AccessRight
        {
            get
            {
                return (this.accessRight == null ? String.Empty : this.accessRight);
            }

            set
            {
                this.accessRight = value;
            }
        }

        #endregion

        /// <summary>
        /// Performs the action of this task.
        /// </summary>
        protected override void InternalExecute()
        {
            MessageQueue queue = null;
            Log.LogMessageFromResources("Msmq.SetPermissions", this.queuePath);
            queue = new MessageQueue();
            queue.Path = this.queuePath;
            MessageQueueAccessRights permission = (MessageQueueAccessRights)Enum.Parse(typeof(MessageQueueAccessRights), this.accessRight, true);

            if (this.denyPermission)
            {
                queue.SetPermissions(this.userName, permission, AccessControlEntryType.Deny);
            }
            else
            {
                queue.SetPermissions(this.userName, permission);
            }

            queue.Close();
        }
    }
}

